Nesting Override ^

Nesting Override

Shortcut: ^Associated Method: uCalc.Rule.NestingAware(bool)

Description: A postfix modifier that instructs a pattern variable to ignore balanced nesting levels (brackets, parentheses, etc.) and stop at the literal next terminal token.

By default, uCalc is "Nesting Aware." This means if a variable is tasked with capturing content inside a bracketed structure, it will intelligently track open and close markers (like ( and )) to ensure it doesn't stop matching prematurely.

The Nesting Override (^) is used to break this structural integrity for specific, surgical transformations.

Default vs. Override Behavior

• Default (Nesting Aware): A pattern like func({x}) matched against func((1+1)) will capture (1+1) into {x}. The engine sees the first ) but knows it belongs to an internal group, so it continues until the "balanced" closing bracket is found.
• Override ({x^}): Appending the ^ symbol tells the engine to stop at the very first occurrence of the terminal token, regardless of whether brackets are balanced or not. In the example above, {x^} would capture ((1+1).

The NestingAware() Method

While the ^ symbol provides per-variable control, you can toggle this behavior globally using the NestingAware() method on the uCalc object.

• uc.NestingAware(true): (Default) All variables respect bracket levels.
• uc.NestingAware(false): All variables behave as if they have the ^ postfix unless otherwise specified.

Examples

1. Succinct (Nesting Awareness Example)

Demonstrating how the engine normally handles nested parentheses versus the override.

New(uCalc::Transformer, t)// Default: captures everything balancedt.FromTo("calc({v})", "RESULT({v})")// Override: stops at the first ')' it seest.FromTo("raw({v^})", "RAW({v})")wl(t.Transform("calc((1+1))")) // Output: RESULT((1+1))wl(t.Transform("raw((1+1))"))  // Output: RAW((1+1)

2. Practical (Surgical Extraction)

In some complex document formats, you may need to stop at the first delimiter even if it appears "inside" a bracketed segment.

New(uCalc::Transformer, t)// We want to capture the function name and the first part of the args// but stop immediately at a comma, even if that comma is inside a nested call.t.FromTo("{@Alpha:f}({args^}, {@All:rest})", "FUNC:{f} ARG1:{args}")wl(t.Transform("process(format(x, y), z)"))

[Expected Output]FUNC:process ARG1:format(x

3. Internal Test (Global vs Local)

Verifying that the global NestingAware setting can be overridden or complemented by the postfix.

// Turn off nesting awareness globallyuc.NestingAware(false)New(uCalc::Transformer, t)// Now, this variable will stop at the first ')' by defaultt.FromTo("test({v})", "GOT:{v}")wl(t.Transform("test((a))"))

[Expected Output]GOT:(a

Strategy & Critique

• Structural Safety: Nesting awareness is one of uCalc's most powerful features, preventing the "leaky capture" issues common in Regular Expressions. The ^ override should be used sparingly.
• Logical Use Case: Use ^ when you are dealing with poorly formatted text or when a bracket character is being used as a literal delimiter rather than a structural container.
• Naming: Renaming the associated method to NestingAware() aligns perfectly with the "Nesting Override" terminology, making the API much more self-documenting.
• See Also: Refer to Topic 786 for Quote Overrides and Topic 780 for Statement Boundary Overrides.